Summary

Follow-up to the black-box test run of the built binary (all ~60 scenarios passed; every finding was documentation lag, fixed here).

Spec ↔ implementation contradiction (the real one)

docs/design.zh-TW.md / docs/design.md §4.2 still said that graft add <repo> --name <existing> "is treated as a deliberate re-point" and updates the entry's repo. The implementation has rejected this with exit 2 since the 2026-06 regression fix, the error message says add never silently re-points an existing entry to another repository, and both testing manuals assert the rejection — only the spec lagged.

Resolution: spec updated to match the implementation (rejection). Rationale, recorded in design.local §10.17: the failure modes are asymmetric — allowing re-points means a pasted-wrong repo URL silently swaps vendored code (worst case for a tool whose pitch is content-hash supply-chain safety), while rejecting costs one explicit remove + add with an honest diff. It also unifies the model: once a name ↔ repo binding exists, any identity change goes through remove + add, same as renaming.

• New REQ-ADD-NOREPOINT row in requirements.md locks it into the coverage ratchet; the existing TestAdd_repointWithNameRejected carries the // spec: annotation (comment-only change).

CACHEDIR.TAG (previously undocumented)

The cache root contains a CACHEDIR.TAG marker: backup tools skip it, and graft cache clean refuses to delete a directory without it — so a misconfigured GRAFT_CACHE_DIR can never rm -rf user data. Now shown in the §5.4 tree, documented in §4.7 clean, and mentioned in testing.md's cache dir row.

Content-store sharding clarified

store/sha256/<xx>/<hex…>/ reads as "full hash under a 2-char bucket", but the entry directory is actually the remaining 62 digits (hash 4e13… → store/sha256/4e/13…/). The §5.4 content-store paragraph now spells this out.

testing.md scenario fixes

• The REQ-ADD-PSEUDO scenario (add mint@main) was order-dependent: on an existing entry, a branch ref resolving to the already-locked commit hits the spec §4.2 "already at" no-op and keeps the tag version, so the old sequence could not reproduce a pseudo-version. It now removes the dep first, with a note explaining the no-op interaction.
• The fixture-repo table no longer pins mint tag versions that drift upstream (v0.0.6 → now v0.0.8).

Verification

• go test -race ./internal/clierr/ passes — both conformance ratchets (§4.6 exit-code table, REQ coverage including the new REQ-ADD-NOREPOINT).
• go test -race -run TestAdd_repointWithNameRejected ./cmd/graft/ passes.
• go build ./... passes.

🤖 Generated with Claude Code